.TH lha_event 1 "13 April 2012" "TrueCL Commands"

.SH NAME
lha_event \- Add, Remove, Change or Query Events

.SH SYNOPSES
.TS
l l.
lha_event	\fB--list\fP [\fB--xml\fP] [\fB-timeout\fP \fIN\fP] [\fB--force\fP]
	[\fB--debug\fP|\fB--verbose\fP|\fB--quiet\fP|\fB--silent\fP] [\fB--lwidth\fP \fIN\fP]
or:
lha_event	\fB--set\fP \fB--name\fP \fIN\fP \fB--event\fP \fIE\fP \fB--text\fP \fIT\fP \fB--type\fP \fIT2\fP
	\fB--send_info\fP \fII\fP [\fB-timeout\fP \fIN\fP] [\fB--force\fP]
	[\fB--debug\fP|\fB--verbose\fP|\fB--quiet\fP|\fB--silent\fP] [\fB--lwidth\fP \fIN\fP]
or:
lha_event	\fB--delete\fP \fB--name\fP \fIN\fP [\fB-timeout\fP \fIN\fP] [\fB--force\fP]
	[\fB--debug\fP|\fB--verbose\fP|\fB--quiet\fP|\fB--silent\fP] [\fB--lwidth\fP \fIN\fP]
.TE

.SH DESCRIPTION
The \fIlha_event(1)\fP command is used to interface with the event handling system that is
built within the TrueCL software. The event monitoring system is a system where particular
events are raised and based on the configuration something may occur. 

By default if an event is raised and nothing is configured against it then nothing will occur.
The following is a list of currently recognised events that the cluster is able to generate:

.TE 12
node.daemon_error
Indicates that a particular daemon has suffered an error. More details should be available in
the content of the generated message.
.TP
node.daemon_warn
Indicates that a non-serious problem has occurred in the specified daemon. 
.TP
node.down
A node has failed unexpectedly.
.TP
node.leave
A node has left the cluster under its own volition. 
.TP
node.join
A node has joined the existing running cluster.
.TP
app.net_route
The specified application route checking has failed on the specified node
where the application is currently running.
.TP
app.start
The specified application has been started.
.TP
app.end
The specified application has stopped.
.TP
app.fail
Application process monitoring has found that one or more processes 
have failed.
.TP
app.monitor
A monitor associated with a particular application has raised an event - additional
text provided will describe the error.
.TP
node.monitor
The node monitoring subsystem has found an error - additional text provided
will indicate the type of the error.
.TP
net.down
The specified network on a specified node has been marked as down. This can
occur if physical interface checking fails for all cards in that network
indicate no connectivity is available.
.TP
net.up
A network previously marked as down (and having no alternatives) has been
found to be available again.
.TP
net.migrate
The specified network topology has been migrated to a different network
card available on the node in question.

.RE
Please note that the majority of these events will be generated from the 
master node in the cluster and so should not be duplicated by every node.

For each of the available events it is possible to one or more records
to indicate what event handling should take place if an error occurs.  At the
moment the following alert handlers are available:

.TP 8
email
Sends an email to a comma-separated list of email addresses. The format of the emails
is a very basic text message, an example might be:

.TS
l.
time: 1334572480
node: node2
cluster: mycl
text:  Appliction Failure [Application monitor 'A:test:testapp' detected failure.]
event_daemon: N/A
event_node: node2
event_app: test
.TE
.RE 8
.TP 8
log
Log event as a single line of text. There are two formats of destination filename
that can be used.
.RS 8
.TP 8
/fullpath
Logs the message to the end of the file on machine where the alert originated.
.TP
host:/fullpath
Logs the message to the end of the file specified in '/fullpath' on the specified
cluster node.
.RE
.RS 8

An example line entry might be as follows:
.TS
l.
time|host|cl|description|daemon|node|net|app
.TE

.TP 4
time
The UNIX time the alert was generated.
.TP
host
The host that has generated the event.
.TP
cl
The name of the cluster generating the event.
.TP
description
A description of the generated alert.
.TP
daemon
The name of the daemon (if applicable) that generated the alert.
.TP
node
The name of the node which generated the alert (often same as host).
.TP
net
The name of the network topology that generated the alert (if applicable).
.TP
app
The name of the application that generated the alert (if applicable).
.RE
.TP 8
socket
Sends a text message of the alert to a specified socket on a specified host.
The host can be any host - does not need to belong to the cluster.
The format of the message is the same as used for the email alert.
.TP
cmd
Run the specified command to generate the alert. In this case various arguments
are appended to the command line, namely:
.RS 8
.TP 8
time
The UNIX time the alert was generated.
.TP
host
The host that has generated the event.
.TP
The name of the cluster generating the event.
.TP
description
A description of the generated alert.
.TP
daemon
The name of the daemon (if applicable) that generated the alert.
.TP
node
The name of the node which generated the alert (often same as host).
.TP
net
The name of the network topology that generated the alert (if applicable).
.TP
app
The name of the application that generated the alert (if applicable).
.RE

Notice that alerts can be generated by various daemons and monitors and it is the
responsibility of the cluster administrator to set up relevant alerting - by default
all alerts will be ignored if no alert mechanism for them is provided.

Defined events are available cluster wide; the node the changes are made on will be
distributed around the other nodes in the cluster as appropriate.

.SH ARGUMENTS
.TP 6
--list
Used to indicate that this invocation is for listing the existing event configuration.
.TP
--set
Used to indicate that this invocation is for adding or replacing an event definition.
.TP
--delete
Indicates that an existing event definition is to be deleted.
.TP
--xml
Used only for the \fB--list\fP list action - outputs the details in valid XML format.
.TP
--timeout N
Indicates the timeout for communicating with various nodes and monitors. If not specified
it will default to 10 seconds.
.TP
--force
Force the action (used for the \fB--delete\fP and \fB--set\fP commands). Normally if one or
more of the nodes cannot be contacted the commands will fail since the configuration database details
kept on all nodes cannot be updated. Use this argument to run the command (and generate the
inconsistency).
.TP
--debug
Generate debug level of output messages.
.TP
--verbose
Generate verbose levels of output (not as much as \fB--debug\fP though).
.TP
--quiet
Only show output for errors and warnings.
.TP
--silent
Only generate output when a serious error occurs.
.TP
--lwidth
Log of the output generated by the logging module. Defaults to the current width of
the terminal if available, 80 otherwise.
.TP
--name
A unique name to use to indicate this event - must not include white space and often
used as a short description such as "node_swap" or "application_proc1" to label
the check.
.TP
--event
The event to perform the \fB--set\fP or \fB--delete\fP command on. The event must appear
in the list of events currently listed above.
.TP
--text
Free format text (so will probably need to enclose in quotes. This is send along with the
error text and is used to describe the potental failure and recovery typically.
.TP
--type
The type of event being created or updated (used for the \fB--set\fP action). This should be
either 'email', 'log', 'cmd' or 'socket'.
.TP
--send_info
This is the additional information that is used with \fB--type\fP argument to define details
of the destination.

.RS 6
.TP /sas/ca
6
email
A comma-separated list of email addresses to send the alerts to.
.TP
log
Where to log messages to. This can be in the format of '/a/full/path' to log locally to
the node generating the alert; 'host:/path' - to write the entry to '/path' on the specified
or. There is a third variation - '%%MASTER%%:/path' - write to '/path' on the node currently
acting as the cluster master.

For remote writing the file specified must already exist otherwise it will not append to it.
.TP
cmd
The actual command to run. This will be run as root and so it is the administrators
responsibility to ensure the file is secure.
.TP
socket
Host:Port format argument indicating where to open the socket to. The host is typically a
host and port can be a number of a service name. The hostname specified can use the
special value '%%MASTER%%' to indicate the current master node of the cluster.
.RE

.SH NOTES
Remember all settings only exist whilst the cluster is running. If the cluster is
stopped and restarted any changes will be lost and settings will return to default.

.SH AUTHOR
The TrueCL software was written by Simon Edwards, (C) 2006-2012, working
for Advantsys Computer Services Ltd - www.advantsys.co.uk.

.SH SEE ALSO
.BR lha_app_probes(1),
.BR lha_app_routes(1),
.BR lha_buildapp(1),
.BR lha_consistency_checker(1),
.BR lha_destroyapp(1),
.BR lha_mond(1).

.SH AVAILABILITY
This utility was specifically written under the GNU GPL license and as required
by such software comes with \fIno warranty or guarantee of any kind\fP. For
more information, please see the following page: truecl.advantsys.co.uk.

